home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / arexx / easyrexx.lha / EasyREXX / Docs / easyrexx.doc < prev   
Encoding:
Text File  |  1995-02-10  |  7.0 KB  |  203 lines
  1. TABLE OF CONTENTS
  2.  
  3. easyrexx.library/AllocARexxContextA()
  4. easyrexx.library/FreeARexxContext()
  5. easyrexx.library/GetARexxMsg()
  6. easyrexx.library/ReplyARexxMsgA()
  7. easyrexx.library/SendArexxCommandA()
  8.  
  9. EasyRexx.library/AllocARexxContextA      EasyRexx.library/AllocARexxContextA
  10.  
  11.   NAME
  12.     AllocARexxContextA  -- allocate a EasyRexx context structure.
  13.     AllocARexxContext   -- varargs stub for AllocARexxContextA.
  14.  
  15.   SYNOPSIS
  16.     requester = AllocARexxContext(tagList);
  17.  
  18.     APTR AllocARexxContextA(struct TagItem *);
  19.  
  20.     context = AllocARexxContext(tag1, ...);
  21.  
  22.     ARexxContext *AllocARexxContext(Tag, ...);
  23.  
  24.   FUNCTION
  25.     Allocates a EasyRexx context data structure.
  26.  
  27.   INPUTS
  28.     taglist - pointer to an optional  tag  list  specifying how to initialize
  29.               the data structure returned by this function.
  30.  
  31.   TAGS
  32.     Defined tags for AllocARexxContext:
  33.  
  34.     ER_Portname     - (UBYTE *) Name of the  public  AREXX  port that will be
  35.                       created.  If a port already  exists with that name, the
  36.                       name  will   be   extended   with   a   serial  number;
  37.                       MYAPP_AREXX,  MYAPP_AREXX.1,  MYAPP_AREXX.2  etc.   The
  38.                       name should always be  given  in uppercase!  The string
  39.                       is  duplicated  so  it  is  safe  to  free  the  string
  40.                       afterwards.  Defaults to EASYREXX.
  41.     ER_Port         - (struct MsgPort  *)  Pointer  to  an  already  existing
  42.                       public named port.  A new port will not be created, but
  43.                       all messages will be received at this specific port.
  44.     ER_CommandTable - (struct ARexxContext *) NULL  terminated table of AREXX
  45.                       commands which your application  supports.  Defaults to
  46.                       NULL.
  47.  
  48.   RESULT
  49.     context - an initialized context data structure, or NULL on failure.
  50.  
  51.   WARNING
  52.     Most data in the context are READ-ONLY and should only be set using tags!
  53.     Note also that if you use  the  tags  ER_Portname and ER_Port in the same
  54.     taglist, easyrexx.library will use last one in the list.
  55.  
  56.   SEE ALSO
  57.     FreeARexxContext()
  58.  
  59. EasyRexx.library/FreeARexxContext          EasyRexx.library/FreeARexxContext
  60.  
  61.   NAME
  62.     FreeARexxContext -- frees resources allocated by AllocARexxContext.
  63.  
  64.   SYNOPSIS
  65.     FreeARexxContext(context);
  66.  
  67.     void FreeARexxContext(struct ARexxContext *);
  68.  
  69.   FUNCTION
  70.     FreeARexxContext()   frees   any    system    resources    allocated   by
  71.     AllocARexxContext(). Once a context has been  freed,  it can no longer be
  72.     used with other calls to GetARexxMsg().
  73.  
  74.   INPUTS
  75.     context - requester obtained from AllocARexxContext(),  or  NULL in which
  76.               case this function does nothing.
  77.  
  78.   SEE ALSO
  79.     AllocARexxContext()
  80.  
  81. EasyRexx.library/GetARexxMsg                   EasyRexx.library/GetARexxMsg
  82.  
  83.   NAME
  84.     GetARexxMsg() -- get an AREXX Message, with EasyRexx processing.
  85.  
  86.     result = GetARexxMsg(context);
  87.  
  88.     BYTE GetARexxMsg(struct ARexxContext *);
  89.  
  90.   DESCRIPTION
  91.     This function gets an AREXX message  from  the  defined AREXX port of the
  92.     application.  If a port was  created (ER_Portname) by AllocARexxContext()
  93.     this port will  have  all  its  messages  replied  with  a RC_FATAL error
  94.     message and then remove the port.   If  no  port was created (ER_Port) no
  95.     messages will be cleared and this function will not remove the port.
  96.  
  97.   INPUTS
  98.     context - pointer to an ARexxContext allocated by AllocARexxContext().
  99.  
  100.   RESULT
  101.     result  - TRUE if a message was received  properly or FALSE when failure.
  102.               If the command received  is  not  recognized by the application
  103.               and hence not in the  commandTable,  the application will never
  104.               be notified.
  105.  
  106.   NOTE
  107.     You must reply to  the  message  after  you  are  done  with it using the
  108.     ReplyARexxMsgA function.
  109.  
  110.   SEE ALSO
  111.     ReplyARexxMsgA()
  112.  
  113. EasyRexx.library/ReplyARexxMsgA              EasyRexx.library/ReplyARexxMsgA
  114.  
  115.   NAME
  116.     ReplyARexxMsgA  -- reply an AREXX message
  117.     ReplyARexxMsg   -- vararg for ReplyARexxMsgA
  118.  
  119.     ReplyARexxMsgA(context, tagList);
  120.  
  121.     void ReplyARexxMsgA(struct ARexxContext *, struct TagItem *);
  122.  
  123.     ReplyARexxMsg(context, tag1, ...);
  124.  
  125.     void ReplyARexxMsg(struct ARexxContext *, Tag, ...);
  126.  
  127.   DESCRIPTION
  128.     This function replies to a message received by a call to GetARexxMsg.
  129.  
  130.   INPUTS
  131.     context - pointer to a context allocated by AllocARexxContext.
  132.     taglist - pointer to an optional tag list  specifying how to reply to the
  133.               AREXX message.
  134.  
  135.   TAGS
  136.     Defined tags for ReplyARexxMsg:
  137.  
  138.     ER_ReturnCode   - (LONG) The code which the  AREXX command should return.
  139.                       Use RC_WARN to give  warnings,  RC_ERROR to indicate an
  140.                       error or RC_FATAL to  indicate  that  a fatal error has
  141.                       occurred.  The value will be  stored in the RC variable
  142.                       in the AREXX-script.  When  present, ER_Result2 will be
  143.                       cleared to NULL.  Defaults to RC_OK.
  144.  
  145.     ER_Result1      - (LONG) Alias for ER_ReturnCode.
  146.  
  147.     ER_Result2      - (LONG) Secondary return code.   Pointer to an argstring
  148.                       created by CreateArgstring().
  149.  
  150.     ER_ResultString - (UBYTE *) Secondary return code.  Will only be returned
  151.                       if,  and  only  if,  the  RXFB_RESULT  bit  is  set  in
  152.                       rm_Action (maintained by  the  system and automatically
  153.                       set when the script  contains  'OPTIONS RESULT').  When
  154.                       present, ER_Result1  will  be  set  to  RC_OK.   If the
  155.                       library somehow could not  return  the string, RC_ERROR
  156.                       will be returned instead.
  157.  
  158.     ER_ResultLong   - (LONG) Secondary return code.  Same as ER_ResultString,
  159.                       but takes (and returns) LONG instead.
  160.  
  161.   WARNING
  162.     All tags returning  data  are  mutual  exclusive.   You  cannot  return a
  163.     returncode, string or number  simultaneously!   May lead to memory-losses
  164.     and unknown effects if tried.
  165.  
  166.   SEE ALSO
  167.     GetARexxMsg()
  168.  
  169. EasyRexx.library/SendARexxCommandA       EasyRexx.library/SendARexxCommandA
  170.  
  171.   NAME
  172.     SendARexxCommandA -- send an AREXX command
  173.     SendARexxCommand  -- varargs stub for SendARexxCommandA().
  174.  
  175.   SYNOPSIS
  176.     result = SendARexxCommandA(command, tagList);
  177.  
  178.     LONG SendARexxCommandA(UBYTE *, struct TagItem *);
  179.  
  180.     result = SendARexxCommand(command, tag1, ...);
  181.  
  182.     LONG SendARexxCommand(UBYTE *, Tag, ...);
  183.  
  184.   FUNCTION
  185.     Sends an AREXX command to an AREXX port.
  186.  
  187.   INPUTS
  188.     command - pointer to NULL terminated  string  that  will  be  sent to the
  189.               AREXX port.
  190.     taglist - pointer to an optional tag  list  which  may be used to control
  191.               features of the function.
  192.  
  193.   TAGS
  194.     Tags defined for this function:
  195.  
  196.     ER_Portname - pointer to a NULL terminated  string  which states the name
  197.                   of the port  the  command  will  be  sent  to.  Defaults to
  198.                   "AREXX".
  199.  
  200.    RESULT
  201.     result -  What the AREXX  command  returned  or  RC_FATAL  if the command
  202.               could not be sent.
  203.